Node / meshtastic / Meshtastic-Android / files / docs / zh-rCN / user / mqtt.md

Displaying Raw • View rendered • Download

---

title: MQTT

parent: User Guide

nav_order: 11

last_updated: 2026-05-13

description: Bridge your mesh to the internet — MQTT broker setup, encryption layers, and map reporting.

aliases:

Tff7b72- mqtt

Tff7b72- internet-bridge

Tc9d1d9 - broker

Tc9d1d9---

Tc9d1d9# MQTT

MQTT bridges your Meshtastic mesh network to the internet, enabling long-range communication beyond radio range.

Tc9d1d9## 总览

The MQTT module connects your node to an MQTT broker, allowing:

Tff7b72- Messages to reach nodes on different physical meshes via the internet

Tff7b72- Integration with home automation and monitoring systems

Tff7b72- Publishing node positions to the public Meshtastic map

Tff7b72- Custom data pipelines for logging and alerting

Tc9d1d9## How It Works

Ta5d6ff```

[Your Node] → Radio → [Gateway Node with WiFi] → MQTT Broker → [Remote Gateway] → Radio → [Remote Node]

```

A gateway node with internet access (WiFi or Ethernet) publishes mesh messages to an MQTT topic. Remote gateways subscribed to the same topic inject those messages into their local mesh.

Tc9d1d9## Configuration

Tc9d1d9### Enabling MQTT

Tff7b721. Navigate to **Settings → Module Config → MQTT**.

Tff7b722. Enable the MQTT module.

Tff7b723. Configure the broker connection:


| Setting | 说明 | 默认 |

| --------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- |

| Server Address | MQTT broker hostname | mqtt.meshtastic.org |

| 用户名称 | Broker authentication | meshdev |

| 密码 | Broker authentication | large4cats |

| Root Topic | Base topic for messages | msh |

| 加密 | Encrypt MQTT payload | Enabled |

| Tf85149~~JSON Output~~ | ⚠️ **Deprecated** — JSON packet support has been removed from firmware; this field is ignored | 禁用 |

| TLS | Secure connection to broker | 禁用 |

| Map Reporting | Report position to public map | 禁用 |

Tc9d1d9### MQTT Proxy on This Phone

If your node has no internet access of its own, it can use the connected phone as its MQTT gateway: enable **MQTT** and **Proxy to client enabled** in the module config, and the app relays MQTT traffic between the radio and the broker over your phone's internet connection.

The **MQTT proxy on this phone** toggle at the top of the MQTT settings screen shows whether this relay is currently running and lets you cut it off (or restart it) immediately — without editing and re-saving the device's MQTT configuration.

Tc9d1d9### Default Meshtastic Broker

The community maintains a public broker at Ta5d6ff`mqtt.meshtastic.org`. This is intended for general use and testing.

Tff7b72> ℹ️ **Note:** Connections to `mqtt.meshtastic.org` always use TLS (port 8883), even if the TLS toggle is off. For any other broker, TLS is used only when you enable it (port 8883 with TLS, 1883 without).

Tff7b72> 🔒 **Privacy:** Messages on the public broker are readable by anyone subscribed. Always use channel encryption for private communications.

Tc9d1d9### Private Broker

For better privacy and control, you can run your own MQTT broker:

Tff7b72- Mosquitto (lightweight, open-source)

Tff7b72- HiveMQ

Tff7b72- EMQX

Configure your node to point to your private broker with appropriate credentials.

Tc9d1d9## Map Reporting

When Map Reporting is enabled, your node publishes its position to the Meshtastic community map:

Tff7b72- Visible at [Tff7b72meshmap.net](Te6edf3https://meshmap.net) and similar community map services

Tff7b72- Only position and node info are shared

Tff7b72- Disable this if you don't want your location publicly visible

Tc9d1d9## Uplink vs Downlink

| Direction | 说明 |

| ------------ | -------------------------------- |

| **Uplink** | Messages from mesh → MQTT broker |

| **Downlink** | Messages from MQTT broker → mesh |

Configure per-channel which directions are active to control message flow and airtime usage.

Tc9d1d9## Message Formats

MQTT uses protobuf message format:

| Format | 说明 | Use case |

| ------------ | ----------------------------------- | -------------------------- |

| **Protobuf** | Binary Meshtastic protobuf encoding | Node-to-node mesh bridging |

Tff7b72> ⚠️ **Note:** JSON output support was removed from firmware. The `json_enabled` setting is still visible in the app for legacy compatibility but has no effect on current firmware versions.

Tc9d1d9## Encryption & Privacy

Understanding the layered encryption model:

Tff7b721. **Channel encryption** happens on the mesh _before_ MQTT. If your channel has a PSK, the MQTT payload is already encrypted — the broker and any subscribers see only the ciphertext.

Tff7b722. **MQTT encryption** (the module setting) adds an additional encryption layer for transit to the broker. This protects metadata and routing information.

Tff7b723. **TLS** encrypts the TCP connection to the broker itself, preventing network-level eavesdropping.

Tff7b72> 🔒 **Important:** The default public channel has a well-known key. Messages on the default channel sent via MQTT are effectively **unencrypted** — anyone can decode them. Always use a custom PSK for private communications.

Tc9d1d9## Best Practices

Tff7b72- Use channel-level encryption (PSK) on channels that bridge to MQTT

Tff7b72- Don't enable MQTT on nodes without internet access (it will buffer and waste memory)

Tff7b72- Use a private broker for sensitive deployments

Tff7b72- Be mindful of airtime when downlinking messages from busy MQTT topics — every downlinked message consumes radio airtime on your local mesh

Tff7b72- Consider enabling uplink-only if you only need to monitor your mesh remotely without injecting messages back

Tc9d1d9## 问题排查

Tc9d1d9### MQTT Not Connecting

Tff7b72- **Check WiFi** — the gateway node must have an active internet connection (WiFi or Ethernet). MQTT does not work over the LoRa radio link itself.

Tff7b72- **Verify credentials** — incorrect username or password will silently fail on most brokers. Double-check for trailing spaces.

Tff7b72- **Firewall** — port 1883 (MQTT) or 8883 (MQTT+TLS) must be open. Some networks block non-standard ports.

Tff7b72- **DNS resolution** — if using a custom broker hostname, verify the node can resolve it. Try the broker's IP address directly.

Tc9d1d9### Messages Not Bridging

Tff7b72- **Check uplink/downlink settings** — if only uplink is enabled, messages flow from mesh to MQTT but not back. Enable downlink on the receiving gateway.

Tff7b72- **Channel mismatch** — both gateways must share the same channel with the same PSK. A mismatch means messages are encrypted with different keys and appear as garbage.

Tff7b72- **Topic mismatch** — ensure both gateways use the same root topic. The default Ta5d6ff`msh` works for the public broker.

Tc9d1d9## Related Topics

Tff7b72- [Tff7b72Settings — Modules & Admin](Te6edf3settings-module-admin) — MQTT module configuration reference

Tff7b72- [Tff7b72Messages & Channels](Te6edf3messages-and-channels) — channel encryption and PSK setup

Tff7b72- [Tff7b72MQTT integration guide](Te6edf3https://meshtastic.org/docs/software/integrations/mqtt) — detailed MQTT documentation on meshtastic.org

---